.NET: fix(dotnet): persist workflow scope aliases consistently - #9749

Motivation & Context

Declarative workflow scope aliases should retain the latest assignment consistently
when state is read, initialized, cleared, or restored.

Description & Review Guide

• What are the major changes? Canonicalize managed scope names before persisted
  state updates, native reads, initialization, and key enumeration. Reuse the
  existing scope-name resolver and add round-trip and state-access coverage.
  Migrate unambiguous legacy Topic entries identified by declarative metadata
  and delete only those entries from the old scope. Reject overlapping entries
  before migration writes, and retry failed
  restores without skipping validation. Share the existing portable decoder so
  migration preserves native storage types rather than coercing numbers.
  Publish restoration updates before post-load hooks or resumed handlers run.
  Register interpreter executors for the same shared restoration phase used by
  Kit executors. Canonicalize aliases in the plain-context sensitivity helpers,
  including state subsequently accessed through expression evaluation.
  Without a formula-state restoration callback, plain helper reads fall back
  to the requested metadata-marked legacy entry without modifying it; writes
  remove only that entry after queuing its canonical value and metadata.
  Ad hoc expression loading uses a read-only formula snapshot instead of queuing
  migration from each reader. Share the collision preflight between plain and
  wrapped assignments, rejecting ambiguous visible same-key Topic entries
  before any value, sidecar, or live formula update. Record separate, versioned
  canonical ownership with Local assignments and migrated values, so concurrent
  raw Topic and canonical Local writes do not misclassify unrelated state.
  Use key-level PortableValue probes instead of enumerating scopes for each
  point operation. Plain helper null updates remove sensitivity and ownership
  metadata together with the value. Preserve both Local and Topic formula names
  when binding the shared canonical state.
  Document the storage decision in proposed ADR 0048.
  If callbacks or restoration publication fail, discard queued updates and
  re-import the checkpoint's persisted state before propagating the original
  error. Index retrieval and post-load hook failures remain outside that rollback
  boundary. Once both restore tasks finish, those later failures discard
  unpublished hook updates without reverting successfully published state.
• What is the impact of these changes? Equivalent scope names address the same
  persisted state. Custom scopes keep their existing behavior; omitted declarative
  scopes use Local.
  Older checkpoints with an identified declarative key in both physical scopes
  and no canonical ownership metadata require explicit reconciliation or a fresh
  session instead of an inferred assignment order.
  Unmarked Topic entries remain untouched, preserving code-first state in mixed
  workflows. Unmarked legacy declarative entries require explicit reconciliation.
  Immediate repeated restores do not leave pending migration updates behind.
  Failed restoration publication can be retried without retaining partially
  applied writes. A later index or hook failure does not undo successful
  publication and leave it inconsistent with live executor state.
  Queued hook updates from a failed restore do not survive into an immediate retry.
  Fan-out expression readers do not queue competing migration writes. Plain
  helper clears do not leave metadata that could claim a later code-first key.
  New canonical ownership permits independently owned raw and canonical values
  to coexist after fan-out publication and restoration; older ambiguous entries
  still reject. Point-helper lookup work stays bounded as pending writes grow.
  Public API signatures are unchanged.
• What do you want reviewers to focus on? Consistency between live formula
  state and persisted state, including alias overwrite and clear operations.

Commands were run from dotnet/.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*CanonicalOwnership*' --no-progress

  • Before ownership tracking and key-level probes: failed, all 16 cases.
    Eight mixed fan-out cases became unreadable, two migrated/raw-reuse cases
    failed restoration, four updates/clears rejected independently owned state,
    and two point-operation cases each enumerated full scopes 64 times.
  • After the correction: passed, all 20 cases, including four added
    unsupported-version cases. Coverage includes both execution modes,
    plain/wrapped assignments, explicit None/Sensitive metadata, fresh JSON restore,
    expression aliases, migration, clear/reuse, and bounded point lookups.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --no-progress

  • Passed: all 1,249 declarative tests.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*LegacyBoundary*' --no-progress

  • Before the correction: failed, all 14 cases. Four fan-out readers queued
    conflicting migration writes, six plain/wrapped collision writes were
    accepted, and four clear/key-reuse cases claimed unrelated code-first values.
  • After the correction: passed, all 14 cases with unchanged assertions.
    Previous read-only helper coverage now expects expression-only reads to
    retain legacy storage; explicit writes and registered pre-hook restoration
    still perform cleanup.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*PlainLegacyHelpers*' --no-progress

  • Before targeted compatibility handling: failed, all 10 cases. Four reads
    missed saved values, four writes left overlapping entries, and two ambiguous
    reads/writes did not reject the overlap.
  • After the correction: passed, all 10 cases with unchanged assertions.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*Checkpoint_Restore_LaterFailureDiscardsHookUpdatesAsync' --no-progress

  • Before late-failure cleanup: failed, all 4 cases retained queued hook values.
  • After the correction: passed, all 4 cases with unchanged assertions.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*PlainSensitivityAliasesRemainConsistentAsync' --no-progress

  • Before plain-context normalization: failed, all 8 cases. Four read null
    after migration and four encountered overlapping entries on another
    restoration or expression evaluation.
  • After the correction: passed, all 8 cases with unchanged assertions.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*Checkpoint_Restore_LaterFailurePreservesPublishedStateAsync' --no-progress

  • Before narrowing rollback: failed, all 4 cases. Index or post-load hook
    failures reverted persisted values while live executor state stayed restored.
  • After the correction: passed, all 4 cases with unchanged assertions.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*ResumeAsync_LegacyCheckpoint*' --no-progress

  • Before shared interpreter restoration: failed, all 6 cases. Four resumed
    assignments encountered conflicting updates; two immediate repeated restores
    rejected pending migration writes.
  • After the correction: passed, all 6 cases with unchanged assertions.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*Checkpoint_Restore_FailedPublicationCanBeRetriedAsync' --no-progress

  • Before restoration rollback: failed, all 4 cases. Two observed retained
    writes after failure; two subsequent restores rejected queued updates.
  • After the correction: passed, all 4 cases with unchanged assertions.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --filter-method '*RestoreAsync_PreservesLatestAliasAssignmentAsync' --no-progress

  • Before implementation changes: failed, with 3 failed and 3 passed cases;
    restored state returned the earlier value instead of the latest assignment.
  • After the correction: passed, all 6 cases with unchanged assertions.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-class '*WorkflowFormulaStateTests' --no-progress

  • Before the follow-up correction: failed, with 4 failed and 20 passed cases.
    Directly seeded legacy values were not restored or cleaned up, and overlapping
    entries were not rejected.
  • After the follow-up correction: passed, all 24 cases, including the original
    alias-assignment regression and repeated conflict rejection.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --no-progress

  • Passed: 2,498 tests across net10.0 and net472; no failures or skips
    in the final run. An earlier run encountered an existing off-thread timing
    failure in RestoreCheckpointAsync_ReloadsFormulaSessionOnEveryLoadAsync;
    the same test failure was reproduced with implementation files restored to
    the published 41207a505 revision before returning to the final implementation.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*RestoreAsync_LegacyMigrationPreservesNativeTypesAsync' --no-progress

  • Before preserving native representations: failed, with 3 failed and 1
    passed case because migrated numeric storage types changed.
  • After the correction: passed as part of the complete project run above.

• dotnet format src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj --no-restore --verbosity quiet

  • Passed.

• dotnet format src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj --no-restore --verbosity quiet

  • Passed.

• dotnet format tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj --no-restore --verbosity quiet

  • Passed.

• dotnet format tests\Microsoft.Agents.AI.Workflows.UnitTests\Microsoft.Agents.AI.Workflows.UnitTests.csproj --no-restore --verbosity quiet

  • Passed.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*ResumeAsync_PublishesLegacyMigration*' --no-progress

  • Before the publication barrier: failed, all 6 cases. Four encountered
    conflicting updates at publication, and two observed missing migrated state
    in another executor's post-load hook.
  • After the barrier: passed, all 6 cases with unchanged assertions.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*ResumeAsync_PreservesUnmarkedTopicEntriesAsync' --no-progress

  • Before ownership filtering: failed, both execution modes rejected
    unrelated unmarked entries as conflicting aliases.
  • After ownership filtering: passed in the complete regression class.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net10.0 --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-class '*WorkflowFormulaStateTests' --no-progress

  • Passed: all 36 cases, including real-state-manager resumes, assignment,
    clearing, post-load visibility, immediate repeated restores, and preservation
    of unrelated code-first entries.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.UnitTests --no-build --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --no-progress

  • Passed: 1,753 tests across net10.0 and net472; no failures or skips.

• dotnet test --project tests\Microsoft.Agents.AI.Workflows.Declarative.UnitTests -f net472 --no-build --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --filter-method '*RestoreCheckpointAsync_ReloadsFormulaSessionOnEveryLoadAsync' --no-progress

  • Failed on the second baseline repetition: the off-thread resumed writer
    changed live state before the test's immediate assertions. Implementation
    equality with 41207a505 was verified before testing. The existing test was
    not weakened or changed.

• dotnet build agent-framework-dotnet.slnx --disable-build-servers -nr:false --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --no-restore --tl:off --verbosity minimal -m:2

  • Passed: full solution, zero warnings and errors.
    After the initial build exhausted the repository drive and was stopped,
    $artifacts was placed on another drive and $outputProps supplied unique
    artifact directory names for projects with duplicate names. These are
    validation-only settings; no repository build configuration changed.

• dotnet test --solution alias-unit-validation.slnx -f net10.0 --no-build --no-restore --artifacts-path $artifacts -p:CustomBeforeDirectoryBuildProps=$outputProps --no-progress --max-parallel-test-modules 2 --ignore-exit-code 8

  • Failed: 9,908 passed, 62 failed, 76 skipped. The temporary solution was
    generated with the repository's New-FilteredSolution.ps1, selecting
    net10.0 unit tests and excluding samples. Failures are outside the changed
    projects: 61 AgentHooks tests could not load agent_hooks_ffi; one
    FileAgentSkillLoader test failed during Windows symlink cleanup with
    UnauthorizedAccessException. The exact failed test names match the previous
    published revision. Both affected projects passed in this run.

Integration tests requiring external services were not run.

Related Issue

N/A - maintainer-directed bugfix; no new issue was opened.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Copilot assisted with implementation, regression tests,
validation, and this pull request description.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.